home *** CD-ROM | disk | FTP | other *** search
/ Languguage OS 2 / Languguage OS II Version 10-94 (Knowledge Media)(1994).ISO / gnu / libg_261.zip / libg_261 / librx / DOC < prev    next >
Text File  |  1994-06-03  |  4KB  |  110 lines
  1. Most of the interfaces are covered by the documentation for GNU regex.
  2.  
  3. This file will accumulate factoids about other interfaces until
  4. somebody writes a manual.
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11. * RX_SEARCH
  12.  
  13. For an example of how to use rx_search, you can look at how
  14. re_search_2 is defined (in rx.c).  Basicly you need to define three
  15. functions.  These are GET_BURST, FETCH_CHAR, and BACK_REF.  They each
  16. operate on `struct rx_string_position' and a closure of your design
  17. passed as void *.
  18.  
  19.     struct rx_string_position
  20.     {
  21.       const unsigned char * pos;    /* The current pos. */
  22.       const unsigned char * string;     /* The current string burst. */
  23.       const unsigned char * end;    /* First invalid position >= POS. */
  24.       int offset;            /* Integer address of  current burst */
  25.       int size;                /* Current string's size. */
  26.       int search_direction;        /* 1 or -1 */
  27.       int search_end;            /* First position to not try. */
  28.     };
  29.  
  30. On entry to GET_BURST, all these fields are set, but POS may be >=
  31. END.  In fact, STRING and END might both be 0.
  32.  
  33. The function of GET_BURST is to make all the fields valid without
  34. changing the logical position in the string.  SEARCH_DIRECTION is a
  35. hint about which way the matcher will move next.  It is usually 1, and
  36. is -1 only when fastmapping during a reverse search.  SEARCH_END
  37. terminates the burst.
  38.  
  39.     typedef enum rx_get_burst_return
  40.       (*rx_get_burst_fn) (struct rx_string_position * pos,
  41.                   void * app_closure,
  42.                   int stop);
  43.                            
  44.  
  45. The closure is whatever you pass to rx_search.  STOP is an argument to
  46. rx_search that bounds the search.  You should never return a string
  47. position from with SEARCH_END set beyond the position indicated by
  48. STOP.
  49.  
  50.  
  51.     enum rx_get_burst_return
  52.     {
  53.       rx_get_burst_continuation,
  54.       rx_get_burst_error,
  55.       rx_get_burst_ok,
  56.       rx_get_burst_no_more
  57.     };
  58.  
  59. Those are the possible return values of get_burst.  Normally, you only
  60. ever care about the last two.  An error return indicates something
  61. like trouble reading a file.  A continuation return means suspend the
  62. search and resume by retrying GET_BURST if the search is restarted.
  63.  
  64. GET_BURST is not quite as trivial as you might hope.  If you have a
  65. fragmented string, you really have to keep two adjacent fragments at
  66. all times, even though the GET_BURST interface looks like you only
  67. need one.  This is because of operators like `word-boundry' that try
  68. to look at two adjacent characters.  Such operators are implemented
  69. with FETCH_CHAR.
  70.  
  71.     typedef int (*rx_fetch_char_fn) (struct rx_string_position * pos,
  72.                      int offset,
  73.                      void * app_closure,
  74.                      int stop);
  75.  
  76. That takes the same closure passed to GET_BURST.  It returns the
  77. character at POS or at one past POS according to whether OFFSET is 0
  78. or 1. 
  79.  
  80. It is guaranteed that POS + OFFSET is within the string being searched.
  81.  
  82.  
  83.  
  84. The last function compares characters at one position with characters
  85. previously matched by a parenthesized subexpression.
  86.  
  87.     enum rx_back_check_return
  88.     {
  89.       rx_back_check_continuation,
  90.       rx_back_check_error,
  91.       rx_back_check_pass,
  92.       rx_back_check_fail
  93.     };
  94.     
  95.     typedef enum rx_back_check_return
  96.       (*rx_back_check_fn) (struct rx_string_position * pos,
  97.                    int lparen,
  98.                    int rparen,
  99.                    unsigned char * translate,
  100.                    void * app_closure,
  101.                    int stop);
  102.                            
  103. LPAREN and RPAREN are the integer indexes of the previously matched
  104. characters.  The comparison should translate both characters being
  105. compared by mapping them through TRANSLATE.  POS is the point at which
  106. to begin comparing.  It should be advanced to the last character
  107. matched during backreferencing.
  108.  
  109.  
  110.